QuickTime 4 Reference

Parameter Descriptions

Each effect component supplies a parameter description data structure that describes in detail the set of parameters that the effect has.

This section describes the parameter description format in detail. You need this information if you are writing an effect component. If you are writing an effect component, you should provide a parameter description as part of an 'atms' resource (see "Supplying Parameter Description Information" for more details).

You may also need this information if you are writing an application that presents its own user interface for setting effect parameters. In this case, you will need to parse parameter descriptions to generate appropriate controls to set parameter values. Most applications can simply use the QTCreateStandardParameterDialog function, and do not need to parse effect parameter descriptions.

Any software that uses an effect can request its parameter description. Typically, the parameter description is then passed to QTCreateStandardParameterDialog or especially, ImageCodecCreateStandardParameterDialog . These functions use the parameter description to display a user interface that allows users to choose the values of the parameters.

Your are free to use the information in an effect's parameter description in other ways. For example, your application can use the default value atoms to construct an effect description.

Parameter descriptions are stored in a QTAtomContainer , and an application retrieves an effect's description by calling ImageCodecGetParameterList . This function takes a component instance and returns the parameter description for that component.

The code shown in Listing 26 opens the component specified in the variable subType . The code sets up the component description, then finds and opens the requested component. It then calls the ImageCodecGetParameterList function to fill out the parameter description for this effect.

Listing 26 Opening the image decompressor component



 
{

    // Set up a component description

    cd.componentType    = 'imdc';       // Effects are image decompressor

                                        // components

    cd.componentSubType = subType;      // This is the name of the effect

                                        //(e.g. 'smpt')

    cd.componentManufacturer    = 0;

    cd.componentFlags           = 0;

    cd.componentFlagsMask       = 0;



    // Find the required component. If it can't be found, generate an

    // error

    if ((theComponent = FindNextComponent(theComponent, &cd))==0)

    {

        err = paramErr;

        goto bail;

    }



    // Open the component

    gCompInstance = OpenComponent(theComponent);



    // Get the parameter description for the effect

    ImageCodecGetParameterList(gCompInstance, &parameterDescription);

}

An application can parse the returned parameter description using the standard QuickTime APIs that query QTAtomContainer data structures. This can be useful if you are writing an application that creates its own interface for users to customize effects.

This section describes the general format of the data returned in a parameter description.

The Parameter Description Format